Documentation Mailing Lists FAQ Frequently Asked Questions v2

Topic: Alerts

From Mitra (mitra[at]earth.path.net):

I am using alerts/mailman integration, - its one of the most painful AA admin procedures, basically you have to create an alert that goes to a mailman group. Here are the steps (note that I've SIMPLIFIED it, removing sub-steps).

This presumes you have:

• A Reader Management slice created
• Mailman installed, and documented elsewhere how to add lists
• Cron working and running the AA cron function for Alerts

1. In the slice you want to send mail from:
   • Create a Alerts View - (known elsewhere as a Selection)
2. Create Alerts Slice and change settings as follows
   • Create a new Alert Template - Cut and paste from Generic Alerts in a separate window
   • Make sure to set the "From" address to something that can be responded to (a human, not a list)
   • Settings -> Alert, set to the new template
   • Selections, add Alerts View created above
   • Reader Management -> set to your Reader Management slice (see note) and "Add or Refresh" (make note of field names for below)
   • Send Emails -> send a test message to yourself, it should come immediately (check in your spam folder, it often gets filtered as such), note this won't look like it does through mailman
3. Go to mailman, create a mailing list - set yourself (a human) as the owner, set to moderate new subscribers
4. Go to your Reader Management slice (see note)
   • Can be useful to Edit item manager to ad a column for this alert (using the field names like alerts1....agxav)
   • Add the address of the new mailing list as a reader, mark it as confirmed, subscribe it to the Alert just created
   • Look for the Alerts welcome mail, which can take time (depending on Cron)
5. Now try and add an item to your slice,
   • Wait for the mail to turn up at the mailing list moderator address,
   • Follow the link into mailman and set the user filter to allow mail from this address to go straight through.

Note that in practice you can only have ONE functioning reader management slice in an entire AA installation since it has email unique - apparently there are historical reasons for this, but it is unclear if there are current reasons.

This is essentially an admin nightmare, do anything even slightly wrong and the mail won't go through, and its very hard to debug.

I believe this could and should be dramatically simplified, we don't have the development resources to build our own mailing list manager in competition to all mailman's functions, better would be to allow an Alerts View to send mail direct to a mailing address - typically the email address of the mailman list.

Reader Management is a special kind of slice that is designed to contain data about subscribed "readers" (aka public web site users). A Reader Management slice can be used to send automated email alerts of new AA items, personalize page views, send bulk target emails, and generally act as a contact database. Anonymous forms can be set-up to allow users to change their subscriptions and contact data in the Reader slice.

1) Go to /apc-aa/misc/forgotten_pwd.php3 (may vary depending where AA is installed)
2) Enter either the username or email address
3) Check the email you will receive in case the user has been found and it's you
4) Visit the url in the email - in fact it's the same but with the temporary key that will let you change the password
5) Change your password

Note: The key expires after 90 minutes

Related FAQ items:

• Alerts step by step walkthrough
• Alerts Admin

AA Alerts are designed to deliver new AA items to users by e-mail. Slice Administrators choose the design and which kind of items from which slices to include, creating Collections. Users subscribe for Collections and receive them optionally once a day, week or month.

A user interface allows users to change their subscriptions. Users are identified by e-mail and they must confirm their e-mail address by a confirmation code received by e-mail to make sure the address is working.

The admin interface allows AA admins to define new Collections, list users subscribed to Collections and list Collections subscribed by users.

Collections

Collections are created by Slice Administrators on the page Slice Admin / Alerts / Collections. They are based on Filters, which are defined in the Digest type of Views.

A Collection is an ordered list of Filters. Each Filter is associated with one Digest and filters items to be sent by using the search form conds[] and sort[]. Digests are views suiting Alerts needs (see below).

You may define Editorial for each Collection, which will be printed before Digests' texts. In the Editorial you can use these aliases:

• _#CONTENTS - will be replaced by a list of collection filters

Digests and Filters

Note: You create filters by typing their DESCRIPTION. You must type at least one description before you can create Collections.

Each view of type Alerts Digest has a set of Filters definitions. Create filters by typing their description. If you want to include all items in the filter, don't fill anything into the "conds[]" field. Otherwise you may fill any conds[] and sort[] definition in the URL shape, e.g.

conds[0][headline........]="human rights"&conds[1][fulltext........]=Bosna

is a filter sorting out items with "human rights" in headline and "Bosna" in fulltext. If you want to order the filtered items, use sort[] (see How to setup searchform in FAQ for details on conds[] and sort[]).

If you want to add more than 2 filters, use Update and than open the view definition again. Two new empty filter boxes will appear.

Sending e-mails

To send the alerts, you must have AA cron set on. Three entries are added to table cron by sql_update.php3, for daily, weekly and monthly sending. You can change the entries if you like. They define the time and date at which all mails are sent. You can't set individual sending times for collections.

E-mails are created so that in e-mail clients supporting HTML users see the HTML form and in clients supporting text only, users see text. The text form is created by deleting all HTML tags. Technically speaking, it is a MIME multi-part/alternative message with a text part and a HTML part.

E-mail headers From:, Reply-To:, Errors-To: and Sender: are configurable for each Collection. Also, you may set these fields for a fictive collection __default__, which is used whenever any of them is not filled for the active Collection. Another fictive collection __subscription__ sets e-mail headers which appear in e-mails sent on user subscription.

User interface

The login screen is shown by misc/alerts/index.php3, the main interface is in misc/alerts/user_filter.php3. It allows to input name and change password. In the other part there is a list of all subscribed collections. A user may change contents of any of the collections. Until she does so, the collection ID remains the same as in the Admin interface. This allows to propagate changes to users: If you do any change in the Admin interface, it will change to all users which didn't modify the collection. But when a user changes a collection, its contents is copied not to modify the common Collection storage. From the user point of view, she doesn't recognize it.

Creating subscription forms

Two scripts are here to simplify subscription forms creation. The first one is add_user_collection.php3, which uses the following required parameters:

• email is the user email address
• collectionid is the numerical collection ID, shown in the admin interface Alerts Collections. It may be an array, allowing to be generated by a multiple select box.
• howoften is one of daily, weekly, monthly
• lang is a two-letter shortcut of the user language (like cz, de, en, es, ja, ro, sk etc.)

and the following optional parameters

• ok_url with URL to jump to if the subscription is successfull
• err_url with URL to jump to if errornous

The standard error page shows an error description. The standard OK page shows information about where to change subscriptions or that the user should confirm her email address if she didn't yet.

The second script print_collections_select.php3 prints a select box to choose a collection by description. It is not necessary to use it, the script only simplifies the maintainance because it gets the collection descriptions from database. It has these optional parameters:

• c[] is a list of collection IDs, e.g. c[]=17&c[]=25
• multiple creates a multiple select box

A simple subscription form may be:

<form name='f' method='post' action='http://www.ecn.cz/apc-aa/misc/alerts/add_user_collection.php3'>
<table>
<tr><td>E-mail:</td><td><input type=text name=email size=50></td></tr>
<tr><td>How often:</td><td><select name=howoften>

<option value=daily>Daily
<option value=weekly>Weekly
<option value=monthly>Monthly

</select></td></tr>
<tr><td>Choose a collection:</td>
<td><!--#include virtual="/apc-aa/misc/alerts/print_collections_select.php3?c[]=7&c[]=11"--></td></tr>
</table>
<input type=submit value="Subscribe">
</form>


But mind the example address www.ecn.cz/aaa is not working, it is only an example.

User Subscription Flow

1. Usually users subscribe on subscription forms in your pages
2. They receive an email message telling them to click on the confirmation URL or copy it to a browser
3. The confirmation URL contains a 4-letter confirmation code which identifies the user
4. After clicking on the URL the login screen appears with the user email filled in and the confirmation code is deleted from the database
5. When the user clicks once more on the URL, the code is not more valid: a subscription page appears
6. If the user doesn't remember her password, she clicks on "Send confirmation", receives another confirmation email and her password is deleted
7. You can use AA Admin E-mails to warn users and / or delete them when they didn't confirm their subscription for a number of days

Sending e-mails manually

You do not need to send e-mails manually, this part is useful for developers. AA cron runs alerts.php3 with two parameters:

• howoften set to one of daily, weekly or monthly
• ss is a stylesheet URL used to format the User Interface

For example

alerts.php3?howoften=weekly

It will work on all items which appeared in Active bin from the last time this script was run. That includes items which were Pending and became Active (even if they are Expired at the moment of sending e-mail), items which were moved from Holding bin and new items added directly to Active bin. Look in the source alerts.php3 for the exact algorithm of selecting items (it's not as easy as described here).

The script itself does not check how often you run it, hence a user can receive a monthly digest every day if you are not careful.

You can use cron.php3 to run the script regularly.

Permissions in Control Panel

Superadmins may as usually access everything.

Slice Admins may access:

• Collections, which use some filter from some digest view defined in some Slice to which they have Admin access.
• Users which are subsribed to some Collection to which they have access. But they may only change settings for Collections to which they have access.

Tables structure

All tables concerned with Alerts have a name starting with alerts_.

User information is stored in alerts_user, collections description in alerts_collection. Filters belonging to collections are in alerts_collection_filter.

Filters are in alerts_digest_filter which is linked 1:n to table view (1 view has n filters). The fields last_xx in alerts_digest_filter include last time when the digest of items filtered by the particular filter was created and text_xx temporarily store the digest text.

Users subscriptions are in alerts_user_filter, each line of which has either a filterid or a collecetionid filled. It allows the users to choose simple filters instead of whole collections but this is not implemented.

This walkthrough does not describe all details, you must look into the FAQ item AA Alerts for them.

To set up Alerts on your computer, first ask some Superadmin to set up default Collections and cron:

1. Jump to Alerts / Collections
2. There should be the special collections with Description __default__ and __subscription__. If you don't have them, something was wrong with sql_update.php3. You should create them in Admin panel, but you must change the "showme" field value to 0 in the database.
3. Set the email headers for the special collections
4. Set up cron on your server
5. Change the values in the table "cron" in the database if you don't like the defaults. There should be 3 rows working with misc/alerts/alerts.php3, sending the daily, weekly and monthly digest. These are created by sql_update.php3.

Now any Slice Admin may work with Alerts:

1. Switch to the slice the items of which you want to send
2. Create a view of type Alerts Digest, fill in a plausible design
3. At the top of the view design page fill some Filter Description and if you want to sent only some of the new slice items, fill the conds[] field with search form-like conds[] and sort[]
4. Jump to Alerts / Collections
5. Create a new Collection, fill at least the Description
6. After clicking on Insert, a list of Filters and Users will appear
7. Add Filters to the Collection

Hurrah, we have a new collection!

Now how to offer it to users? On any of your web pages, create a subscription form. See AA Alerts for details. If you want to see a list of users subscribed to your collection, click on Edit in Alerts / Collections.

There are several places where APC-AA sends mail, and it can be confusing, especially since it is really easy to configure them wrongly so they don't work, and little help for figuring out why. Lets consider 4 cases. The Bugs and Weaknesses of each method are shown because they may help pick which method to use, and also help guide as to places for further development.

Slice Admin or Editor wants notification of new items added to Hold bin, or edited or whatever.

Use the Email Notification functionality, here you can specify different messages to be sent when messages are added / edited to Active / Hold bins, and different recipient lists, so for example you can create a message to an Editor whenever a new message arrives in a Hold bin, and maybe a different message to the sysadmin when an item is moved into the Active bin (usually by the Editor). The message could be just something like "An item has been posted in Xyz slice" or by using aliases can include any fields of the item posted.

Bug/Weakness: You can't use aliases in Subject line, this might be fixed in some version (but is unlikely to be a priority!)
Limitation: The members of the list can only be changed by a slice admin, so don't use this for Alerts ...

A number of people want to receive items posted to a slice

Use a reader management slice (see doc/reader.html) in conjunction with Alerts (doc/alerts.html).

Bug/Weakness: its complex to setup, and frequently people don't succeed, if you don't follow the Tutorial Step by Step (in doc/alerts.html) you probably won't get it to work.

Bug/Weakness: In particular it requires creating an anonymous form, which depends very much on the way its being used (e.g. called from something.shtml or site.php3). One possible development fix would be creating a PHP3 script that took the slice-id of an Alerts module as a parameter and did this much more simply.

Bug/Weakness: documentation says 5.3a: View with type "Alerts Digest", when it means "Alerts Selection Set".

A number of people want to be in an email discussion, i.e. all posting to each other.

Use a Reader Management Slice (see doc/reader.html) in conjunction with Mailman, APC-AA is used to manage the mailman list

Bug/Weakness: you can no longer manage the lists (subscribe/unsubscribe) by email to the Mailman account once you've done this, mailman will almost certainly be sending out email telling the users they can!

Bug/Weakness: You have to understand both apc-aa AND mailman to get this to work since doc/reader.html refers to tasks that require knowing where to find and how to configure mailman.

Bug/Weakness: There is no link between information in a slice, or discussions, and the email discussion, i.e. this is not - like yahoo groups - a web OR mail interface to the same set of data.

Reports of failure (Jason Diceman) partly due to server setup

People wish to receive copies of new comments in Discussions by Email

See "FAQ/Discussions as Mail List", this allows a field in each item to specify a mailing list.

Bug/Weakness: This field has to be added to every item, it can't be specified at the slice level (make the field Required but not Shown and set a default). This is particularly difficult if you want to retrofit discussions to an existing slice, or something coming in over RSS.

Bug/Weakness: This can only go to a single email address, so you have to manage the list somewhere else outside APC-AA (there is no way to for example link it to Alerts).

Bug/Weakness: It doesn't appear to work, sends blank emails.

Summary

Note:

There is no integration for receiving email, although there has been discussion (where?) about posting articles by mail

This a tutorial for creating a simple alert module and subscription form, similar to the Sandbox subscription demo at http://actionapps.org/reader_mngmt/sandbox_subscribe.shtml. The alert is for all new items in a slice and the subscription require s only email address and sending frequency inputs, no password or selection of slices in this version. Subscribers can update their alert settings (e.g. change email address, modify frequency, and unsubscribe) by clicking on a unique link at the bottom of each alert they recieve.

The tutorial assumes you are already comfrotable creating and administrating slices and designing views in ActionApps.

Step 1: Create a Reader Management Slice

First you must have a Reader Management slice to store subscriber information. If you already hace a Reader slice, then you can skip this step, but keep in mind the Reader slice used in this example is called "My Readers".

1. AA > New Slice: Create a new slice from the “Reader Management Minimal” template with the name “My Readers”
2. Set “Allow anonymous posting” to “Active”
3. Set “Allow anonymous editing” to “Authorized by a password field”

You now have a Readers slice called "My Readers" that will store each alert subscriber as one item. It also possible to add more fields to store additional data about your subscribers, but that's another tutorial (coming soon).

Next we need to select what items subscribers can be alerted to.

Step 2: Create a Selection of Items to be “Alerted”

An alert modules requires selections from slices. A selection is a condition on an alerts view of a slice. It's a bit confusing but will make more sense once we go through the complete alert module production process.

In this case, we have selected to alert users about new items from the important slice called “My Slice”.

In My Slice, create a new view, type “Alerts Selection Set”. Set field vaules as:

Alerts Selection Set: “My Slice alert views”

Group by selections (ignore for now)

Alerts Selection 1 Description: “All My Slice Items”

conds[] (ignore for now)

Alerts Selection 2 Description and conds[] (ignore for now)

Fulltext URL: (URL of fulltext view use for _#HDLN_URL)

Fill the rest of the fields as a simple listing view, probably similar to your index view.

Click Update

You now have an alerts selection called “All My Slice Items”. Once you are more comfortable with alerts, you can add more selections that use conds[] to allow users to filter in only certain types of items, but that's another tutorial (coming soon).

Step 3: Create an Alerts Module

Next step is to create an alerts module that will send your newly created alert selection.

1. AA > Create New > Alert, settings:
   • name*: “My Alerts Module”
   • form URL*: this will be the public SHTML file with an anonymous form for readers to edit their subscription e.g. http://mysite.com/myalerts/update.shtml (see Step 4 below).
   • update (you can go back and edit more later)
2. Selections > Insert “All My Slice Items” from the menu (notice there are also shortcut links at the bottom for quick access to the slices with alerts and editing the alert views).
3. Click on Reader management, Synchronization with Reader Management Slice, change to “My Readers“ (the page will refresh)
4. Click on 'Add or refresh fields' at the bottom. A message “2 field(s) added” appears.

Your alert module now contains alert selection "All My Slice Items" and My Readers slice contains two new input fields: “How Often” and “Selections”. You can goto the My Readers fields admin page to see these new fields. If they don't show up, go back to alert module > Reader Management and click on ‘Add or refresh fields’.

More selections can be added later. Everytime you add a section you will need to go back to your alert module > Reader management and click on ‘Add or refresh fields’.

You can now test your alert module by subcribing yourself using: My Readers > Add New Item: input your email address, check "email confirmed", set "How Often" to "instant" and check "Selections: All My Slice Items"

Then go to My Slice and add a new item. You should shortly there after receive an emal from the alert module announcing the new addition. You will notice the alert module messages use ECN related text by default. You can customize your welcome and alert messages at any time (see Step 5). But first let's set-up some public subscription forms...

Step 4: Create a Subscribe Form (and Related Pages)

To allow users to subscribe to your alerts, you will need to create a form using ‘Anonymous Form Wizard’. You should also have an OK page that tells users to check their inbox for an email confirmation and a another page with an anonymous form for updating subscription settings. Thus you will need to create three files, e.g.:

http://mysite.com/myalerts/subscribe.shtml - Invitation to subscribe using anonymous form.

http://mysite.com/myalerts/subscribe_ok.shtml - A notice telling users to "Check your inbox for an email confirmation".

http://mysite.com/myalerts/update.shtml - A subscrition settings update page using anonymous form, accessed only from a link within alert messages generated using _#COLLFORM alias (set in Alerts Admin - Settings: form URL.

To create the required anonymous form for the subscribe.shtml and update.shtml pages...

1. Within My Readers > Slice Admin > fields: check Required for 'Email' and uncheck Required and Show for 'Password'.
2. Slice Admin > Anonymous Form Wizard
   • Fill the 'OK page' with URL to subscribe_ok.shtml and 'Error page' with URL to subscribe.shtml
   • Uncheck all fields except ' Email', 'How often' and 'Selections'. Click on 'Show form'.
3. Copy the form HTML and paste into the file subscribe.shtml. Add some preable text and upload to the URL you specified.
4. Upload subscribe_ok.shtml to specified URL.
5. Paste the same form HTML in to update.shtml. In the <form> change the value of the two hidden fileds "err_url" and "ok_url" to the update.shtml URL. Upload.

You should now have a page for users to subscribe to the alert (e.g. origianl sandbox alert subscribe form) that when submitted correctly leads to the OK page saying "Check your inbox for an email confirmation". In the confirmation/welcome email there should be link with unique ID pointing to the the update.shtml URL. When visited, this page will confirm the email address and allow thye user to modify their subscription settings, inluding change their setting to "not subscribed".

You should test this subscritpion process, including updating subscription settings. Add some new items to My Slice and check that subscribers receive them as expeceted.

Make Forms Pretty

You may also want to simplify the anonymous form by hiding the selection check box and possibly the "how often" select box. To hide the selection checkbox, just change the input type from "checkbox" to "hidden", and remove the surrounding text. To hide the "how often" select box you need to create a hidden input with the name and one value pulled from the "how often" select box. The final cleaned up form could look like the sandbox alert subscribe form.

You may also want to similarily modify the update, see sandbox alert update form.

Step 5: Customize Your Alert Messages

If you haven't already, you will want to customize the alert welcome message (sent once upon subscription for email confirmation) and the alert message template.

Alert Welcome Message

Like any important text, you should probably use a word processor to write and check spelling of the message to sent. You can use HTML or plain text. You will want to include:

• A clear subject line e.g. "Organization X - alerts subscription confirmation"
• Where the message is coming from and why
• A clear request to confirm the subscription by going to _#COLLFORM (alias for update.shtml)
• An explanation of what the alert is for and what kind of content
• Details about your organization.
• Contact details for any technical problems.

To update the test, go to you Alert Module > Settings and click edit icon beside welcome email select box. Both the subject and body processes aliases and {} commands.

Alert Message Template

The alert message template is edited the same as Welcome Message, except that _#FILTERS_ will be replace by the views of the new selections. You will want to include:

• A clear subject line e.g. "Organization X - My Slice Alert"
• Where the message is coming from and why
• "_#FILTERS_" where the selection views of new items will be inserted.
• Details about your organization.
• Contact details for any technical problems.
• A reminder that subscription settings can be updated by going to _#COLLFORM

The views of selections can accessed through My Alerts Module > Selections > click on selection name. It is probably best to put the introduction to each slice's items within the top HTML for each slices Alerts Selection Set view. This is more important when there are multiple selection options within an alert module.

Tips

Filtering readers who are not yet confirmed

Change the design of the Item Manager in Slice Admin to show the alias _#MAILCONF. This alias shows “yes” or “no”. But it is created by the f_c function and the values in the database are 0 or 1. Thus give “0” and not “no” into the Search box.
Filtering readers receiving a selection: Add the Alerts Selections to Item Manager. Create an alias using the function f_h with the parameter , (comma). You will see the selection IDs prefixed by f. Now you understand why you should enter something like “f45” into the Search box.

Customize Result Messages

To customize result messages, (i.e.. confirmation, error or update messages at the top right of anonymous forms) use show_results.php3: Copy the script from doc/script/show_result.php3 to the same location where you created myalerts.shtml.
When creating anon form: Fill the URL of yours show_result.php3 and check the box “Use a PHP script ...”

This FAQ interface was developed by Jason at Commons.ca

APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC) APC - Internet and ICTs for social justice and development